Restores an offscreen pixel image to the state that you saved with the GetPixelsState function.

void SetPixelsState (
    PixMapHandle pm, 
    GWorldFlags state
);

Parameter descriptions

pm

A handle to an offscreen pixel map.

state

Flags, which you usually save with the GetPixelsState function. You can use either of the constants pixelsPurgeable or pixelsLocked here.

Because only an unlocked memory block can be purged, SetPixelsState calls the UnlockPixels and AllowPurgePixels functions if the state parameter specifies the pixelsPurgeable flag. If the state parameter does not specify the pixelsPurgeable flag, SetPixelsState makes the base address for the offscreen pixel image unpurgeable.

If the state parameter does not specify the pixelsLocked flag, SetPixelsState allows the base address for the offscreen pixel image to be moved.

DISCUSSION

The SetPixelsState function changes the state of the memory allocated for an offscreen pixel image to the state indicated in the state parameter.

After using GetPixelsState and before using SetPixelsState, your application can temporarily alter the offscreen graphics world by using the AllowPurgePixels function to temporarily mark the memory block for its offscreen pixel map as purgeable, the NoPurgePixels function to make it unpurgeable, the LockPixels function to prevent it from being moved, and the UnlockPixels function to unlock it.

SPECIAL CONSIDERATIONS

The SetPixelsState function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)